// Copyright 2023 Google LLC

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//     http://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

#![warn(missing_docs)]

#![cfg_attr(all(doc, RUSTC_NIGHTLY), feature(doc_auto_cfg))]

//! This crate provides a convenient framework to develop

//! [Vulkan layers](https://github.com/KhronosGroup/Vulkan-Loader/blob/main/docs/LoaderLayerInterface.md)

//! in Rust on top of the [ash](https://crates.io/crates/ash) crate. If you are not familiar how to

//! write a Vulkan layer, [this C++ tutorial](https://renderdoc.org/vulkan-layer-guide.html) by

//! Baldur Karlsson is a good reference to start with.

//!

//! Key features provided by this crate includes:

//!

//! * Support the look-up map fashion of implementing a Vulkan layer.

//!

//!   The look-up maps for `VkDevice` and `VkInstance` are handled by this crate.

//!

//! * Implement `vkGet*ProcAddr` automatically.

//!

//!   This is a non-trivial work to comply with the spec, because of extensions and the

//!   required/supported Vulkan API level. See the

//!   [spec](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetInstanceProcAddr.html)

//!   of `vkGetInstanceProc` for details.

//!

//! * Handle dispatch tables, `vkCreateInstance` and `vkCreateDevice`.

//!

//!   This mainly includes using the `vkGet*ProcAddr` function pointer correctly, and advancing the

//!   `VkLayer*CreateInfo::u::pLayerInfo` link list. One common mistake in layer implementation

//!   in `vkCreateDevice` is to call `getInstanceProcAddr(VK_NULL_HANDLE, "vkCreateDevice")` to

//!   obtain the function pointer to `vkCreateDevice`. According to

//!   [the spec](https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetInstanceProcAddr.html#_description),

//!   `getInstanceProcAddr` should return `NULL`. This framework helps you avoid bugs like this.

//!

//! Note that object wrapping is not supported by this crate, and we don't plan such support,

//! because object wrapping requires us to intercept ALL Vulkan commands related to one handle type,

//! so it can't handle unknown commands. In addition, object wrapping is more complicated because it

//! is required to call loader callback on every dispatchable handle creation and destruction.

//!

//! # Overview

//!

//! The primary types in this crate are the [`Layer`] trait and the [`Global`] struct. The user

//! implements the [`Layer`] trait for a type `T`, and the [`Global<T>`] will include all necessary

//! functions needed to export from this dynamic link library. With the help of the

//! [`declare_introspection_queries`] macro, the user can export those functions in oneline.

//!

//! ```

//! use ash::{self, vk};

//! use once_cell::sync::Lazy;

//! use std::sync::Arc;

//! use vulkan_layer::{

//!     declare_introspection_queries, Global, Layer, LayerManifest, StubDeviceInfo,

//!     StubGlobalHooks, StubInstanceInfo,

//! };

//!

//! // Define the layer type.

//! #[derive(Default)]

//! struct MyLayer(StubGlobalHooks);

//!

//! // Implement the Layer trait.

//! impl Layer for MyLayer {

//!     type GlobalHooksInfo = StubGlobalHooks;

//!     type InstanceInfo = StubInstanceInfo;

//!     type DeviceInfo = StubDeviceInfo;

//!     type InstanceInfoContainer = StubInstanceInfo;

//!     type DeviceInfoContainer = StubDeviceInfo;

//!

//!     fn global_instance() -> impl std::ops::Deref<Target = Global<Self>> + 'static {

//!         static GLOBAL: Lazy<Global<MyLayer>> = Lazy::new(Default::default);

//!         &*GLOBAL

//!     }

//!

//!     fn manifest() -> LayerManifest {

//!         Default::default()

//!     }

//!

//!     fn global_hooks_info(&self) -> &Self::GlobalHooksInfo {

//!         &self.0

//!     }

//!

//!     fn create_instance_info(

//!         &self,

//!         _: &vk::InstanceCreateInfo,

//!         _: Option<&vk::AllocationCallbacks>,

//!         _: Arc<ash::Instance>,

//!         _next_get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr,

//!     ) -> Self::InstanceInfoContainer {

//!         Default::default()

//!     }

//!

//!     fn create_device_info(

//!         &self,

//!         _: vk::PhysicalDevice,

//!         _: &vk::DeviceCreateInfo,

//!         _: Option<&vk::AllocationCallbacks>,

//!         _: Arc<ash::Device>,

//!         _next_get_device_proc_addr: vk::PFN_vkGetDeviceProcAddr,

//!     ) -> Self::DeviceInfoContainer {

//!         Default::default()

//!     }

//! }

//!

//! // Define the global type from the layer type.

//! type MyGlobal = Global<MyLayer>;

//! // Export C functions.

//! declare_introspection_queries!(MyGlobal);

//! ```

//! The user can provide their own types that implement different traits to intercept different

//! commands and custom the layer behavior:

//! * [`GlobalHooks`], [`InstanceHooks`], [`DeviceHooks`]: Implements the interception to different

//!   Vulkan commands based on the dispatch types.

//! * [`GlobalHooksInfo`], [`InstanceInfo`], [`DeviceInfo`]: Container of [`GlobalHooks`],

//!   [`InstanceHooks`], [`DeviceHooks`]. Provide the list of commands to intercept for the

//!   framework. Can be automatically implemented through the [`auto_deviceinfo_impl`],

//!   [`auto_globalhooksinfo_impl`], [`auto_instanceinfo_impl`] macros from the [`GlobalHooks`],

//!   [`InstanceHooks`], [`DeviceHooks`] implementation respectively.

//! * [`Layer`]: Provide the metadata of a layer through [`LayerManifest`], e.g. the name, version,

//!   exported extensions of the layer. Provide the storage for the [`Global`] object. Container of

//!   [`GlobalHooksInfo`] type. The factory type of the [`InstanceInfo`], [`DeviceInfo`] types.

//!

//! # Usage

//!

//! You can check a live example in `examples/hello-world`.

//!

//! First, create a Rust lib crate.

//! ```bash

//! $ mkdir vulkan-layer-rust-example

//! $ cd vulkan-layer-rust-example

//! $ cargo init --lib

//!      Created library package

//! ```

//!

//! Second, modify the crate type to `cdylib` and set the panic behavior to abort in `Cargo.toml`.

//! ```toml

//! [lib]

//! crate-type = ["cdylib"]

//!

//! [profile.dev]

//! panic = "abort"

//!

//! [profile.release]

//! panic = "abort"

//! ```

//! We need to set panic to abort to avoid unwinding from Rust to the caller(most likely C/C++),

//! because unwinding into other language from Rust is

//! [undefined behavior](https://doc.rust-lang.org/beta/nomicon/unwinding.html).

//!

//! If you want to try the layer on Android, also modify the crate name to

//! `VkLayer_vendor_rust_example`, because Android requires that the layer shared object library

//! follow a specific name convention.

//! ```toml

//! [lib]

//! name = "VkLayer_vendor_rust_example"

//! ```

//!

//! Third, set up the dependency in `Cargo.toml`. In my case, I checkout the project repository in

//! the same directory where the `vulkan-layer-rust-example` folder lives.

//! ```toml

//! [dependencies]

//! vulkan-layer = { path = "../vk-layer-for-rust/vulkan-layer" }

//! ```

//! Other dependencies.

//! ```bash

//! cargo add ash once_cell

//! ```

//!

//! Fourth, implement the layer trait in `lib.rs`.

//! ```

//! use ash::{self, vk};

//! use once_cell::sync::Lazy;

//! use std::sync::Arc;

//! use vulkan_layer::{

//!     declare_introspection_queries, Global, Layer, LayerManifest, StubDeviceInfo,

//!     StubGlobalHooks, StubInstanceInfo,

//! };

//!

//! #[derive(Default)]

//! struct MyLayer(StubGlobalHooks);

//!

//! impl Layer for MyLayer {

//!     type GlobalHooksInfo = StubGlobalHooks;

//!     type InstanceInfo = StubInstanceInfo;

//!     type DeviceInfo = StubDeviceInfo;

//!     type InstanceInfoContainer = StubInstanceInfo;

//!     type DeviceInfoContainer = StubDeviceInfo;

//!

//!     fn global_instance() -> impl std::ops::Deref<Target = Global<Self>> + 'static {

//!         static GLOBAL: Lazy<Global<MyLayer>> = Lazy::new(Default::default);

//!         &*GLOBAL

//!     }

//!

//!     fn manifest() -> LayerManifest {

//!         let mut manifest = LayerManifest::default();

//!         manifest.name = "VK_LAYER_VENDOR_rust_example";

//!         manifest.spec_version = vk::API_VERSION_1_1;

//!         manifest.description = "Rust test layer";

//!         manifest

//!     }

//!

//!     fn global_hooks_info(&self) -> &Self::GlobalHooksInfo {

//!         &self.0

//!     }

//!

//!     fn create_instance_info(

//!         &self,

//!         _: &vk::InstanceCreateInfo,

//!         _: Option<&vk::AllocationCallbacks>,

//!         _: Arc<ash::Instance>,

//!         _next_get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr,

//!     ) -> Self::InstanceInfoContainer {

//!         Default::default()

//!     }

//!

//!     fn create_device_info(

//!         &self,

//!         _: vk::PhysicalDevice,

//!         _: &vk::DeviceCreateInfo,

//!         _: Option<&vk::AllocationCallbacks>,

//!         _: Arc<ash::Device>,

//!         _next_get_device_proc_addr: vk::PFN_vkGetDeviceProcAddr,

//!     ) -> Self::DeviceInfoContainer {

//!         println!("Hello from the Rust Vulkan layer!");

//!         Default::default()

//!     }

//! }

//! ```

//!

//! Fifth, export functions through the [`declare_introspection_queries`] macro

//! ```

//! # use ash::{self, vk};

//! # use once_cell::sync::Lazy;

//! # use std::sync::Arc;

//! # use vulkan_layer::{

//! #     declare_introspection_queries, Global, Layer, LayerManifest, StubDeviceInfo,

//! #     StubGlobalHooks, StubInstanceInfo,

//! # };

//! #

//! # #[derive(Default)]

//! # struct MyLayer(StubGlobalHooks);

//! #

//! # impl Layer for MyLayer {

//! #     type GlobalHooksInfo = StubGlobalHooks;

//! #     type InstanceInfo = StubInstanceInfo;

//! #     type DeviceInfo = StubDeviceInfo;

//! #     type InstanceInfoContainer = StubInstanceInfo;

//! #     type DeviceInfoContainer = StubDeviceInfo;

//! #

//! #     fn global_instance() -> impl std::ops::Deref<Target = Global<Self>> + 'static {

//! #         static GLOBAL: Lazy<Global<MyLayer>> = Lazy::new(Default::default);

//! #         &*GLOBAL

//! #     }

//! #

//! #     fn manifest() -> LayerManifest {

//! #         let mut manifest = LayerManifest::default();

//! #         manifest.name = "VK_LAYER_VENDOR_rust_example";

//! #         manifest.spec_version = vk::API_VERSION_1_1;

//! #         manifest.description = "Rust test layer";

//! #         manifest

//! #     }

//! #

//! #     fn global_hooks_info(&self) -> &Self::GlobalHooksInfo {

//! #         &self.0

//! #     }

//! #

//! #     fn create_instance_info(

//! #         &self,

//! #         _: &vk::InstanceCreateInfo,

//! #         _: Option<&vk::AllocationCallbacks>,

//! #         _: Arc<ash::Instance>,

//! #         _next_get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr,

//! #     ) -> Self::InstanceInfoContainer {

//! #         Default::default()

//! #     }

//! #

//! #     fn create_device_info(

//! #         &self,

//! #         _: vk::PhysicalDevice,

//! #         _: &vk::DeviceCreateInfo,

//! #         _: Option<&vk::AllocationCallbacks>,

//! #         _: Arc<ash::Device>,

//! #         _next_get_device_proc_addr: vk::PFN_vkGetDeviceProcAddr,

//! #     ) -> Self::DeviceInfoContainer {

//! #         println!("Hello from the Rust Vulkan layer!");

//! #         Default::default()

//! #     }

//! # }

//! declare_introspection_queries!(Global::<MyLayer>);

//! ```

//!

//! Sixth, build and check the exported symbol of the build artifacts, and we should see Vulkan

//! introspection APIs are exported.

//!

//! On Windows, use

//! [`dumpbin`](https://learn.microsoft.com/en-us/cpp/build/reference/dumpbin-reference?view=msvc-170)

//! ```cmd

//! $ dumpbin /exports .\target\debug\VkLayer_vendor_rust_example.dll

//! Microsoft (R) COFF/PE Dumper Version 14.36.32537.0

//! Copyright (C) Microsoft Corporation.  All rights reserved.

//!

//!

//! Dump of file .\target\debug\VkLayer_vendor_rust_example.dll

//!

//! File Type: DLL

//!

//!   Section contains the following exports for VkLayer_vendor_rust_example.dll

//!

//!     00000000 characteristics

//!     FFFFFFFF time date stamp

//!         0.00 version

//!            1 ordinal base

//!            6 number of functions

//!            6 number of names

//!

//!     ordinal hint RVA      name

//!

//!           1    0 000F1840 vkEnumerateDeviceExtensionProperties = vkEnumerateDeviceExtensionProperties

//!           2    1 000F1820 vkEnumerateDeviceLayerProperties = vkEnumerateDeviceLayerProperties

//!           3    2 000F1800 vkEnumerateInstanceExtensionProperties = vkEnumerateInstanceExtensionProperties

//!           4    3 000F17E0 vkEnumerateInstanceLayerProperties = vkEnumerateInstanceLayerProperties

//!           5    4 000F1890 vkGetDeviceProcAddr = vkGetDeviceProcAddr

//!           6    5 000F1870 vkGetInstanceProcAddr = vkGetInstanceProcAddr

//!

//!   Summary

//!

//!         1000 .data

//!        11000 .pdata

//!        37000 .rdata

//!         2000 .reloc

//!       171000 .text

//! ```

//! On Linux, use [`objdump`](https://linux.die.net/man/1/objdump).

//! ```bat

//! $ objdump -TC target/debug/libVkLayer_vendor_rust_example.so

//!

//! target/debug/libVkLayer_vendor_rust_example.so:     file format elf64-x86-64

//!

//! DYNAMIC SYMBOL TABLE:

//! (omit some irrelevant symbols...)

//! 00000000000fad20 g    DF .text  0000000000000022  Base        vkEnumerateDeviceExtensionProperties

//! 00000000000face0 g    DF .text  000000000000001c  Base        vkEnumerateInstanceExtensionProperties

//! 00000000000fad50 g    DF .text  0000000000000018  Base        vkGetInstanceProcAddr

//! 00000000000facc0 g    DF .text  0000000000000018  Base        vkEnumerateInstanceLayerProperties

//! 00000000000fad00 g    DF .text  000000000000001c  Base        vkEnumerateDeviceLayerProperties

//! 00000000000fad70 g    DF .text  0000000000000018  Base        vkGetDeviceProcAddr

//! ```

//!

//! Seventh, create the layer manifest file named `rust_example_layer.json` right beside the built

//! artifact. If targeting Android, the json manifest file is not needed.

//!

//! For Windows,

//! ```json

//! {

//!     "file_format_version" : "1.2.1",

//!     "layer": {

//!         "name": "VK_LAYER_VENDOR_rust_example",

//!         "type": "INSTANCE",

//!         "library_path": ".\\VkLayer_vendor_rust_example.dll",

//!         "library_arch" : "64",

//!         "api_version" : "1.1.0",

//!         "implementation_version" : "0",

//!         "description" : "Rust test layer"

//!     }

//! }

//! ```

//!

//! For Linux,

//! ```json

//! {

//!     "file_format_version" : "1.2.1",

//!     "layer": {

//!         "name": "VK_LAYER_VENDOR_rust_example",

//!         "type": "INSTANCE",

//!         "library_path": "./libVkLayer_vendor_rust_example.so",

//!         "library_arch" : "64",

//!         "api_version" : "1.1.0",

//!         "implementation_version" : "0",

//!         "description" : "Rust test layer"

//!     }

//! }

//! ```

//! This json file will define an explicit layer named `VK_LAYER_VENDOR_rust_example`.

//!

//! Eighth, use [`VkConfig`](https://github.com/LunarG/VulkanTools/blob/main/vkconfig/README.md)

//! (i.e. Vulkan Configurator) to force enable this explicit layer, and launch the vkcube

//! application through `VkConfig`. In the log view, we should see the

//! `"Hello from the Rust Vulkan layer!"` log line. For Android, follow

//! [this instruction](https://developer.android.com/ndk/guides/graphics/validation-layer) to enable

//! the layer. [`println!`] won't write to logcat, so one needs to change the layer implementation

//! to write to the logcat.

//!

//! # Global initialization and clean up

//!

//! See [the][Layer#initialization] [document][Layer#global-clean-up] of [`Layer`] for details.

//!

//! # Extensions

//!

//! TODO

//!

//! # Synchronization

//!

//! TODO

//!

//! # Safety

//!

//! TODO

//!

//! # API stability

//!

//! TODO

use ash::vk::{self, Handle};

use bytemuck::cast_slice;

use log::{error, warn};

use std::{

    borrow::Borrow,

    collections::{BTreeMap, BTreeSet},

    ffi::{c_char, c_void, CStr, CString},

    ptr::{null, null_mut, NonNull},

    sync::{Arc, Mutex},

};

extern crate self as vulkan_layer;

mod bindings;

mod global_simple_intercept;

mod layer_trait;

mod lazy_collection;

#[cfg(any(feature = "_test", test))]

pub mod test_utils;

#[cfg(feature = "unstable")]

pub mod unstable_api;

#[cfg(not(feature = "unstable"))]

mod unstable_api;

mod vk_utils;

use bindings::vk_layer::{VkLayerDeviceCreateInfo, VkLayerFunction, VkLayerInstanceCreateInfo};

pub use bindings::vk_layer::{VkLayerDeviceLink, VkLayerInstanceLink};

pub use global_simple_intercept::Extension;

use global_simple_intercept::{DeviceDispatchTable, InstanceDispatchTable, VulkanCommand};

pub use layer_trait::{

    DeviceHooks, DeviceInfo, ExtensionProperties, GlobalHooks, GlobalHooksInfo, InstanceHooks,

    InstanceInfo, Layer, LayerManifest, LayerResult, VulkanCommand as LayerVulkanCommand,

};

use unstable_api::{ApiVersion, IsCommandEnabled, LazyCollection};

pub use vk_utils::{fill_vk_out_array, VulkanBaseInStructChain, VulkanBaseOutStructChain};

use vk_utils::{ptr_as_uninit_mut, slice_from_raw_parts, slice_to_owned_strings};

pub use vulkan_layer_macros::{

    auto_deviceinfo_impl, auto_globalhooksinfo_impl, auto_instanceinfo_impl,

    declare_introspection_queries,

};

trait DispatchableObject: vk::Handle + Copy {

    type DispatchKey: From<usize>;

    fn get_dispatch_key(&self) -> Self::DispatchKey {

        assert_eq!(

            std::mem::size_of::<Self>(),

            std::mem::size_of::<*const *const c_void>()

        );

        // Safe, because all dispatchable objects can be cast to void **. See details at

        // https://github.com/KhronosGroup/Vulkan-Loader/blob/35b005a5792f6e4c2931d62a37324923f1a71c79/docs/LoaderDriverInterface.md#driver-dispatchable-object-creation.

        let key = unsafe {

            // We use transmute instead of Handle::as_raw here to avoid integer to pointer cast, and

            // allow the miri tests with tree borrows to work with this test. See

            // https://github.com/ash-rs/ash/issues/996 for details.

            let dispatch_table_ptr = std::mem::transmute_copy::<Self, *const *const c_void>(self);

            std::ptr::read(dispatch_table_ptr)

        };

        (key as usize).into()

    }

}

#[repr(transparent)]

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

struct InstanceDispatchKey(usize);

impl From<usize> for InstanceDispatchKey {

    fn from(value: usize) -> Self {

        Self(value)

    }

}

impl DispatchableObject for vk::Instance {

    type DispatchKey = InstanceDispatchKey;

}

impl DispatchableObject for vk::PhysicalDevice {

    type DispatchKey = InstanceDispatchKey;

}

#[repr(transparent)]

#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]

struct DeviceDispatchKey(usize);

impl From<usize> for DeviceDispatchKey {

    fn from(value: usize) -> Self {

        Self(value)

    }

}

impl DispatchableObject for vk::Device {

    type DispatchKey = DeviceDispatchKey;

}

impl DispatchableObject for vk::CommandBuffer {

    type DispatchKey = DeviceDispatchKey;

}

impl DispatchableObject for vk::Queue {

    type DispatchKey = DeviceDispatchKey;

}

struct InstanceInfoWrapper<T: Layer> {

    get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr,

    dispatch_table: InstanceDispatchTable,

    api_version: ApiVersion,

    enabled_extensions: BTreeSet<Extension>,

    // instance_commands and device_commands are recalculated on every vkCreateInstance, so that

    // the layer can decide which commands to intercept dynamically.

    instance_commands: Box<[VulkanCommand]>,

    device_commands: Box<[VulkanCommand]>,

    is_create_device_hooked: bool,

    customized_info: T::InstanceInfoContainer,

}

struct PhysicalDeviceInfoWrapper {

    owner_instance: vk::Instance,

    properties: vk::PhysicalDeviceProperties,

}

struct DeviceInfoWrapper<T: Layer> {

    dispatch_table: DeviceDispatchTable,

    get_device_proc_addr: vk::PFN_vkGetDeviceProcAddr,

    api_version: ApiVersion,

    enabled_extensions: BTreeSet<Extension>,

    // device_commands are recalculated on every vkCreateDevice, so that the layer can decide

    // which commands to intercept dynamically.

    device_commands: Box<[VulkanCommand]>,

    customized_info: T::DeviceInfoContainer,

}

/// A struct that implements all necessarily functions for a layer given a type that implements

/// [`Layer`].

///

/// The layer implementation should use [`Global::default`] to construct a [`Global`] object.

/// When all `VkInstance`s and `VkDevice`s are destroyed, the drop of [`Global`] is no-op if the

/// drop of `T` is no-op under such circumstances. See [the][Layer#initialization]

/// [document][Layer#global-clean-up] of [`Layer`] for details on global initialization and

/// clean-up.

///

/// This is supposed to be a global singleton for a layer to store all necessary data to implement a

/// Vulkan layer including dispatch tables, maps between the Vulkan objects and their wrappers, etc.

pub struct Global<T: Layer> {

    instance_map: Mutex<LazyCollection<BTreeMap<InstanceDispatchKey, Arc<InstanceInfoWrapper<T>>>>>,

    physical_device_map:

        Mutex<LazyCollection<BTreeMap<vk::PhysicalDevice, Arc<PhysicalDeviceInfoWrapper>>>>,

    device_map: Mutex<LazyCollection<BTreeMap<DeviceDispatchKey, Arc<DeviceInfoWrapper<T>>>>>,

    /// Access to the underlying `T`.

    // layer_info can't be lazily constructed when the first VkInstance is created, because we want

    // to guarantee that T::default is only called once during the lifetime of Global, so that the

    // client can put global state in T, and can perform global initialization(e.g. the global

    // logger) in T::default. If the client needs Global to be trivially destructible, the client

    // must guarantee that T is also trivially destructible.

    pub layer_info: T,

    get_instance_addr_proc_hooked: bool,

}

impl<T: Layer> Global<T> {

    fn instance() -> impl std::ops::Deref<Target = Self> + 'static {

        T::global_instance()

    }

    fn get_instance_info(

        &self,

        instance: impl DispatchableObject<DispatchKey = InstanceDispatchKey>,

    ) -> Option<Arc<InstanceInfoWrapper<T>>> {

        self.instance_map

            .lock()

            .unwrap()

            .get()

            .get(&instance.get_dispatch_key())

            .map(Arc::clone)

    }

    fn create_physical_device_infos<U: Borrow<vk::PhysicalDevice>>(

        &self,

        instance: vk::Instance,

        physical_devices: impl IntoIterator<Item = U>,

    ) {

        for 
physical_device27
 in physical_devices {

            let mut physical_device_map = self.physical_device_map.lock().unwrap();

            let mut physical_device_map = physical_device_map.get_mut_or_default();

            if let Some(
physical_device_info2
) = physical_device_map.get(physical_device.borrow()) {

                assert_eq!(physical_device_info.owner_instance, instance);

                continue;

            }

            let instance_info = self.get_instance_info(instance).unwrap_or_else(|| {

                panic!("Unknown VkInstance handle: {:#018x}", instance.as_raw())

            });

            let properties = unsafe {

                instance_info

                    .dispatch_table

                    .core

                    .get_physical_device_properties(*physical_device.borrow())

            };

            physical_device_map.insert(

                *physical_device.borrow(),

                Arc::new(PhysicalDeviceInfoWrapper {

                    owner_instance: instance,

                    properties,

                }),

            );

        }

    }

    fn get_device_info(

        &self,

        device: impl DispatchableObject<DispatchKey = DeviceDispatchKey>,

    ) -> Option<Arc<DeviceInfoWrapper<T>>> {

        self.device_map

            .lock()

            .unwrap()

            .get()

            .get(&device.get_dispatch_key())

            .map(Arc::clone)

    }

    fn get_physical_info(

        &self,

        physical_device: vk::PhysicalDevice,

    ) -> Option<Arc<PhysicalDeviceInfoWrapper>> {

        self.physical_device_map

            .lock()

            .unwrap()

            .get()

            .get(&physical_device)

            .map(Arc::clone)

    }

    extern "system" fn create_instance(

        create_info: *const vk::InstanceCreateInfo,

        allocator: *const vk::AllocationCallbacks,

        p_instance: *mut vk::Instance,

    ) -> vk::Result {

        let p_next_chain = unsafe { create_info.as_ref() }

            .map(|create_info| create_info.p_next as *mut vk::BaseOutStructure)

            .unwrap_or(null_mut());

        let mut p_next_chain: VulkanBaseOutStructChain = unsafe { p_next_chain.as_mut() }.into();

        let layer_create_info = p_next_chain.find_map(|out_struct| {

            let out_struct = out_struct as *mut vk::BaseOutStructure;

            let layer_create_info = unsafe {

                ash::match_out_struct!(match out_struct {

                    out_struct @ VkLayerInstanceCreateInfo => {

                        out_struct

                    }

                    _ => {

                        return None;

                    }

                })

            };

            if layer_create_info.function == VkLayerFunction::VK_LAYER_LINK_INFO {

                Some(layer_create_info)

            } else {

                None

            }

        });

        let layer_create_info = match layer_create_info {

            Some(layer_create_info) => layer_create_info,

            None => {

                error!("failed to find the VkLayerInstanceCreateInfo struct in the chain.");

                return vk::Result::ERROR_INITIALIZATION_FAILED;

            }

        };

        let layer_info = unsafe { layer_create_info.u.pLayerInfo.as_ref() }.unwrap();

        layer_create_info.u.pLayerInfo = layer_info.pNext;

        let get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr =

            layer_info.pfnNextGetInstanceProcAddr;

        let global = Self::instance();

        let hooked =

            T::GlobalHooksInfo::hooked_commands().contains(&LayerVulkanCommand::CreateInstance);

        let layer_result = if hooked {

            global.layer_info.global_hooks().create_instance(

                unsafe { create_info.as_ref() }.unwrap(),

                layer_info,

                unsafe { allocator.as_ref() },

                p_instance,

            )

        } else {

            LayerResult::Unhandled

        };

        match layer_result {

            LayerResult::Handled(Ok(())) => {}

            LayerResult::Handled(Err(e)) => return e,

            LayerResult::Unhandled => {

                let 
get_proc_addr48
 = |name: &CStr| -> *const c_void {

                    let fp = unsafe { get_instance_proc_addr(vk::Instance::null(), name.as_ptr()) };

                    if let Some(
fp56
) = fp {

                        return fp as *const _;

                    }

                    std::ptr::null()

                };

                let entry = vk::EntryFnV1_0::load(get_proc_addr);

                let ret: vk::Result =

                    unsafe { (entry.create_instance)(create_info, allocator, p_instance) };

                if !
matches!0
(ret, vk::Result::SUCCESS) {

                    return ret;

                }

            }

        };

        let instance = *unsafe { p_instance.as_ref() }.unwrap();

        let ash_instance = unsafe {

            ash::Instance::load(

                &ash::vk::StaticFn {

                    get_instance_proc_addr,

                },

                instance,

            )

        };

        let create_info = unsafe { create_info.as_ref() }.unwrap();

        let enabled_extensions = unsafe {

            slice_from_raw_parts(

                create_info.pp_enabled_extension_names,

                create_info.enabled_extension_count,

            )

        };

        let enabled_extensions = unsafe { slice_to_owned_strings(enabled_extensions) }

            .filter_map(|extension_name| 
match extension_name.as_str().try_into()8
 {

                Ok(extension) => Some(extension),

                Err(e) => {

                    warn!(

                        "Failed to recognize the extension {}: {}",

                        extension_name, e

                    );

                    None

                }

            
}8
)

            .collect();

        let api_version = unsafe { create_info.p_application_info.as_ref() }

            .map(|app_info| 
app_info.api_version8
)

            .unwrap_or(0);

        let api_version = if api_version == 0 {

            ApiVersion { major: 1, minor: 0 }

        } else {

            api_version.into()

        };

        let ash_instance = Arc::new(ash_instance);

        let customized_info = global.layer_info.create_instance_info(

            create_info,

            unsafe { allocator.as_ref() },

            Arc::clone(&ash_instance),

            get_instance_proc_addr,

        );

        let is_create_device_hooked = global

            .layer_info

            .hooked_instance_commands(customized_info.borrow())

            .any(|command| 
command == LayerVulkanCommand::CreateDevice8
);

        let instance_commands = global.create_instance_commands(customized_info.borrow());

        let device_commands = global.create_device_commands(customized_info.borrow(), None);

        {

            let key = instance.get_dispatch_key();

            let mut instance_map = global.instance_map.lock().unwrap();

            let mut instance_map = instance_map.get_mut_or_default();

            if instance_map.contains_key(&key) {

                error!(

                    "duplicate instances: instance {:?} already exists",

                    instance

                );

                return vk::Result::ERROR_INITIALIZATION_FAILED;

            }

            instance_map.insert(

                key,

                Arc::new(InstanceInfoWrapper {

                    get_instance_proc_addr,

                    dispatch_table: InstanceDispatchTable::load(

                        get_instance_proc_addr,

                        ash_instance,

                    ),

                    api_version,

                    enabled_extensions,

                    instance_commands,

                    device_commands,

                    is_create_device_hooked,

                    customized_info,

                }),

            );

        }

        vk::Result::SUCCESS

    }

    extern "system" fn destroy_instance(

        instance: vk::Instance,

        allocator: *const vk::AllocationCallbacks,

    ) {

        if instance == vk::Instance::null() {

            return;

        }

        let dispatch_key = instance.get_dispatch_key();

        let global = Self::instance();

        let instance_info = global

            .instance_map

            .lock()

            .unwrap()

            .get_mut_or_default()

            .remove(&dispatch_key);

        let instance_info = instance_info.unwrap();

        let instance_info = match Arc::try_unwrap(instance_info) {

            Ok(instance_info) => instance_info,

            Err(_) => panic!(

                "This should be the sole instance dispatch table reference for instance {:?}.",

                instance

            ),

        };

        global

            .physical_device_map

            .lock()

            .unwrap()

            .get_mut_or_default()

            .retain(|_, physical_device_info| 
physical_device_info.owner_instance != instance25
);

        unsafe {

            (instance_info.dispatch_table.core.fp_v1_0().destroy_instance)(instance, allocator)

        };

    }

    extern "system" fn enumerate_physical_devices(

        instance: vk::Instance,

        p_physical_device_count: *mut u32,

        p_physical_devices: *mut vk::PhysicalDevice,

    ) -> vk::Result {

        let global = Self::instance();

        let ash_instance = &global

            .get_instance_info(instance)

            .expect("Must be a valid VkInstance")

            .dispatch_table

            .core;

        let res = unsafe {

            (ash_instance.fp_v1_0().enumerate_physical_devices)(

                instance,

                p_physical_device_count,

                p_physical_devices,

            )

        };

        if (res == vk::Result::SUCCESS || 
res == vk::Result::INCOMPLETE0
)

            && !p_physical_devices.is_null()

        {

            let physical_device_count = unsafe { p_physical_device_count.as_ref() }.unwrap();

            let physical_devices =

                unsafe { slice_from_raw_parts(p_physical_devices, *physical_device_count) };

            global.create_physical_device_infos(instance, physical_devices);

        }

        res

    }

    extern "system" fn enumerate_physical_device_groups(

        instance: vk::Instance,

        p_physical_device_group_count: *mut u32,

        p_physical_device_group_properties: *mut vk::PhysicalDeviceGroupProperties,

    ) -> vk::Result {

        let global = Self::instance();

        let ash_instance = &global

            .get_instance_info(instance)

            .expect("Must be a valid VkInstance")

            .dispatch_table

            .core;

        let res = unsafe {

            (ash_instance.fp_v1_1().enumerate_physical_device_groups)(

                instance,

                p_physical_device_group_count,

                p_physical_device_group_properties,

            )

        };

        if (res == vk::Result::SUCCESS || res == vk::Result::INCOMPLETE)

            && !p_physical_device_group_count.is_null()

        {

            let physical_device_group_count =

                *unsafe { p_physical_device_group_count.as_ref() }.unwrap();

            let physical_device_groups = unsafe {

                slice_from_raw_parts(

                    p_physical_device_group_properties,

                    physical_device_group_count,

                )

            };

            let physical_devices =

                physical_device_groups

                    .iter()

                    .flat_map(|physical_device_group| {

                        &physical_device_group.physical_devices[..physical_device_group

                            .physical_device_count

                            .try_into()

                            .unwrap()]

                    });

            global.create_physical_device_infos(instance, physical_devices);

        }

        res

    }

    extern "system" fn create_device(

        physical_device: vk::PhysicalDevice,

        create_info: *const vk::DeviceCreateInfo,

        p_allocator: *const vk::AllocationCallbacks,

        p_device: *mut vk::Device,

    ) -> vk::Result {

        let create_info = unsafe { create_info.as_ref() }.unwrap();

        let mut p_next_chain: VulkanBaseOutStructChain =

            unsafe { (create_info.p_next as *mut vk::BaseOutStructure).as_mut() }.into();

        let layer_create_info = p_next_chain.find_map(|out_struct| {

            let out_struct = out_struct as *mut vk::BaseOutStructure;

            let layer_create_info = unsafe {

                ash::match_out_struct!(match out_struct {

                    out_struct @ VkLayerDeviceCreateInfo => {

                        out_struct

                    }

                    _ => {

                        return None;

                    }

                })

            };

            if layer_create_info.function == VkLayerFunction::VK_LAYER_LINK_INFO {

                Some(layer_create_info)

            } else {

                None

            }

        });

        let layer_create_info = match layer_create_info {

            Some(layer_create_info) => layer_create_info,

            None => {

                error!("failed to find the VkLayerDeviceCreateInfo struct in the chain.");

                return vk::Result::ERROR_INITIALIZATION_FAILED;

            }

        };

        let layer_link = unsafe { layer_create_info.u.pLayerInfo.as_ref() }.unwrap();

        layer_create_info.u.pLayerInfo = layer_link.pNext;

        let get_instance_proc_addr: vk::PFN_vkGetInstanceProcAddr =

            layer_link.pfnNextGetInstanceProcAddr;

        let get_device_proc_addr: vk::PFN_vkGetDeviceProcAddr = layer_link.pfnNextGetDeviceProcAddr;

        let global = Self::instance();

        let physical_device_info = global

            .get_physical_info(physical_device)

            .expect("physical device must be a valid VkPhysicalDevice.");

        let instance_info = global

            .get_instance_info(physical_device_info.owner_instance)

            .expect("The owner instance of this physical device must be registered.");

        let create_device_name = CString::new("vkCreateDevice").unwrap();

        let next_create_device = unsafe {

            get_instance_proc_addr(

                instance_info.dispatch_table.core.handle(),

                create_device_name.as_ptr(),

            )

        };

        let next_create_device: vk::PFN_vkCreateDevice =

            unsafe { std::mem::transmute(next_create_device) };

        let mut create_info = *create_info;

        let requested_extensions = unsafe {

            slice_from_raw_parts(

                create_info.pp_enabled_extension_names,

                create_info.enabled_extension_count,

            )

        };

        let requested_extensions =

            unsafe { slice_to_owned_strings(requested_extensions) }.collect::<Vec<_>>();

        let create_device_res = if instance_info.is_create_device_hooked {

            instance_info

                .customized_info

                .borrow()

                .hooks()

                .create_device(

                    physical_device,

                    &create_info,

                    layer_link,

                    unsafe { p_allocator.as_ref() },

                    unsafe { ptr_as_uninit_mut(p_device) }.unwrap(),

                )

        } else {

            LayerResult::Unhandled

        };

        let layer_manifest = T::manifest();

        match create_device_res {

            LayerResult::Handled(Ok(())) => {}

            LayerResult::Handled(Err(e)) => return e,

            LayerResult::Unhandled => {

                let enabled_extensions = requested_extensions

                    .iter()

                    .filter_map(|extension_name| {

                        let extension_name_cstring = CString::new(extension_name.clone())

                            .unwrap_or_else(|e| {

                                panic!("Failed to create CString from {}: {}", extension_name, e)

                            });

                        let 
extension: Extension11
 = match extension_name.as_str().try_into() {

                            Ok(extension) => extension,

                            Err(_) => return Some(extension_name_cstring),

                        };

                        if layer_manifest

                            .device_extensions

                            .iter()

                            .any(|layer_extension| 
layer_extension.name == extension9
)

                        {

                            None

                        } else {

                            Some(extension_name_cstring)

                        }

                    
}12
)

                    .collect::<Vec<_>>();

                let enabled_extensions = enabled_extensions

                    .iter()

                    .map(|extension_name| 
extension_name.as_ptr()5
)

                    .collect::<Vec<_>>();

                create_info.enabled_extension_count = enabled_extensions.len().try_into().unwrap();

                create_info.pp_enabled_extension_names = if enabled_extensions.is_empty() {

                    null()

                } else {

                    enabled_extensions.as_ptr()

                };

                let res = unsafe {

                    next_create_device(physical_device, &create_info, p_allocator, p_device)

                };

                if res != vk::Result::SUCCESS {

                    return res;

                }

            }

        }

        let device = *unsafe { p_device.as_ref() }.unwrap();

        let ash_instance = Arc::clone(&instance_info.dispatch_table.core);

        let ash_device = unsafe {

            // ash will also try to load instance-level dispatchable commands with

            // vkGetDeviceProcAddr. Although that won't end up with undefined behavior, and we

            // should always expect NULL returned according to the spec, we may see Android vulkan

            // loader complaining about internal vkGetDeviceProcAddr called for <function name>,

            // which should be benign.

            ash::Device::load(

                &vk::InstanceFnV1_0 {

                    get_device_proc_addr,

                    ..ash_instance.fp_v1_0().clone()

                },

                device,

            )

        };

        let ash_device = Arc::new(ash_device);

        let enabled_extensions = requested_extensions

            .iter()

            .filter_map(|name| {

                let extension_name: Option<Extension> = name.as_str().try_into().ok();